<?php
/**
 * PureMVC Port to PHP originally translated by Asbjørn Sloth Tønnesen
 *
 * @author Omar Gonzalez :: omar@almerblank.com
 * @author Hasan Otuome :: hasan@almerblank.com
 *
 * Created on Sep 24, 2008
 * PureMVC - Copyright(c) 2006-2008 Futurescale, Inc., Some rights reserved.
 * Your reuse is governed by the Creative Commons Attribution 3.0 Unported License
 */

/**
 * The interface definition for a PureMVC Facade.
 *
 * <P>
 * The Facade Pattern suggests providing a single
 * class to act as a central point of communication
 * for a subsystem. </P>
 *
 * <P>
 * In PureMVC, the Facade acts as an interface between
 * the core MVC actors (Model, View, Controller) and
 * the rest of your application.</P>
 *
 * @see org.puremvc.php.interfaces.IModel IModel
 * @see org.puremvc.php.interfaces.IView IView
 * @see org.puremvc.php.interfaces.IController IController
 * @see org.puremvc.php.interfaces.PureMVC_Command_Interface PureMVC_Command_Interface
 * @see org.puremvc.php.interfaces.PureMVC_Observer_Notification_Interface PureMVC_Observer_Notification_Interface
 */
interface PureMVC_Facade_Interface
{
	/**
	 * Register an <code>PureMVC_Proxy_Interface</code> with the <code>Model</code> by name.
	 *
	 * @param proxy the <code>PureMVC_Proxy_Interface</code> to be registered with the <code>Model</code>.
	 */
	public function registerProxy( PureMVC_Proxy_Interface $proxy );

	/**
	 * Retrieve a <code>PureMVC_Proxy_Interface</code> from the <code>Model</code> by name.
	 *
	 * @param proxyName the name of the <code>PureMVC_Proxy_Interface</code> instance to be retrieved.
	 * @return the <code>PureMVC_Proxy_Interface</code> previously regisetered by <code>proxyName</code> with the <code>Model</code>.
	 */
	public function retrieveProxy( $proxyName );

	/**
	 * Check to see if a Proxy is registered with the Model.
	 *
	 * @param proxyName name of the <code>PureMVC_Proxy_Interface</code> instance to check for.
	 */
	public function hasProxy( $proxyName );

	/**
	 * Remove an <code>PureMVC_Proxy_Interface</code> instance from the <code>Model</code> by name.
	 *
	 * @param proxyName the <code>PureMVC_Proxy_Interface</code> to remove from the <code>Model</code>.
	 */
	public function removeProxy( $proxyName );

	/**
	 * Register an <code>PureMVC_Command_Interface</code> with the <code>Controller</code>.
	 *
	 * @param noteName the name of the <code>PureMVC_Observer_Notification_Interface</code> to associate the <code>PureMVC_Command_Interface</code> with.
	 * @param commandClassRef a reference to the <code>Class</code> of the <code>PureMVC_Command_Interface</code>.
	 */
	public function registerCommand( $noteName, $commandClassRef );

	/**
	 * Notify <code>Observer</code>s of an <code>PureMVC_Observer_Notification_Interface</code>.
	 *
	 * @param note the <code>PureMVC_Observer_Notification_Interface</code> to have the <code>View</code> notify observers of.
	 */
	public function notifyObservers( PureMVC_Observer_Notification_Interface $note );

	/**
	 * Register an <code>IMediator</code> instance with the <code>View</code>.
	 *
	 * @param mediator a reference to the <code>IMediator</code> instance
	 */
	public function registerMediator( PureMVC_Mediator_Interface $mediator );

	/**
	 * Retrieve an <code>IMediator</code> instance from the <code>View</code>.
	 *
	 * @param mediatorName the name of the <code>IMediator</code> instance to retrievve
	 * @return the <code>IMediator</code> previously registered with the given <code>mediatorName</code>.
	 */
	public function retrieveMediator( $mediatorName );

	/**
	 * Check to see if a Mediator is registered with the View.
	 *
	 * @param mediatorName name of the <code>IMediator</code> instance to check for.
	 */
	public function hasMediator( $mediatorName );

	/**
	 * Remove a <code>IMediator</code> instance from the <code>View</code>.
	 *
	 * @param mediatorName name of the <code>IMediator</code> instance to be removed.
	 */
	public function removeMediator( $mediatorName );

	/**
	 * Send a <code>PureMVC_Observer_Notification_Interface</code>.
	 *
	 * <P>
	 * Convenience method to prevent having to construct new
	 * notification instances in our implementation code.</P>
	 *
	 * @param notificationName the name of the notification to send
	 * @param body the body of the notification (optional)
	 * @param type the type of the notification (optional)
	 */
	public function sendNotification( $notificationName, $body = null, $type = null );

}